home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995 February: Tool Chest / Dev.CD Feb 95 / Dev.CD Feb 95.toast / Sample Code / Pascal Sample 3.0B10 / Source / SampleUtilities.p < prev    next >
Encoding:
Text File  |  1993-10-13  |  12.5 KB  |  350 lines  |  [TEXT/MPS ]
  1. (******************************************************************************
  2. *
  3. *    Apple Macintosh Developer Technical Support
  4. *
  5. *    Interfaces for the utility routines
  6. *
  7. *    Program:    Sample 3.0
  8. *    File:        SampleUtilties.p - Pascal implementation
  9. *
  10. *    by:            Matt Deatherage
  11. *
  12. *    Copyright © 1988-1993 Apple Computer, Inc.
  13. *    All rights reserved.
  14. *
  15. *******************************************************************************
  16. * 
  17. * This file contains many utility routines, ones which don't really fit
  18. * in with the rest of the organization but are still useful, necessary
  19. * and proper.  Some of these routines are from Macintosh Technical Notes
  20. * or Inside Macintosh, and others are just useful encapsulations of
  21. * techniques we needed within Sample.
  22. * 
  23. ******************************************************************************)
  24.  
  25. UNIT SampleUtilities;
  26.  
  27. INTERFACE
  28.  
  29. (*******************************************************************************
  30. * Used Units
  31. *******************************************************************************)
  32.  
  33. USES Errors, Resources, Packages, ToolUtils, PrintTraps, AppleTalk, Processes,
  34.      PPCToolbox, EPPC, Notification, AppleEvents, Features;
  35.  
  36. (*******************************************************************************
  37. * Constants
  38. *******************************************************************************)
  39.  
  40. CONST
  41.     kMissingAppNameStr = - 16396;     { 'STR ' with our application name in it }
  42.  
  43.     rActionAlertBase = 5000;         { base resource ID for close/quit Alert }
  44.     kClosing = 1;                    { string to use when closing }
  45.     kQuitting = 2;                     { string to use when quitting }
  46.  
  47.  
  48.     { Buttons in the "Save changes to document?" Alert }
  49.  
  50.     kSave = 1;                        { "Save" }
  51.     kCancel = 2;                    { "Cancel" }
  52.     kDontSave = 3;                    { "Don’t save" }
  53.  
  54.     { Resource IDs for alerts for errors for HandleFileError }
  55.  
  56.     rIOError = 2001;                 { Got an I/O error on a file }
  57.     rFileAlreadyOpen = 2002;         { That file's already open so you 
  58.                                       can't open it again }
  59.     rNoPermission = 2003;             { You don't have permission for that file }
  60.     rSomeWeirdError = 2004;         { An uncommon error happened }
  61.     rDiskWriteProt = 2005;             { the disk is write-protected }
  62.     rFileVersionInconsistent = 2006;{ the internal file version is later than
  63.                                       what we recognize }
  64.     rFileDiskLocked = 2007;            { can't open with write permission }
  65.     rSaveChanges = 2008;             { ask if we should save changes before
  66.                                       closing or quitting }
  67.     rCantWriteFile = 2009;            { Couldn't write the file to disk }
  68.  
  69.     rUntitledStrings = 1003;        { 'STR#' resource with untitled strings }
  70.     kUntitledWithSpaceString = 1;    { "untitled " }
  71.     kUntitledNoSpaceString = 2;        { "untitled" }
  72.  
  73.     { key code constants for the ClassifyKey routine }
  74.  
  75.     kEnterKey = 3;
  76.     kDeleteKey = 8;
  77.     kTabKey = 9;
  78.     kReturnKey = 13;
  79.     kEscapeKey = 27;
  80.     kLeftArrowKey = 28;
  81.     kRightArrowKey = 29;
  82.     kUpArrowKey = 30;
  83.     kDownArrowKey = 31;
  84.     kPeriodKey = 46;
  85.  
  86.     { bit numbers for the flags in ClassifyKey }
  87.     
  88.     kDigitKeyBit = 0;
  89.     kLetterKeyBit = 1;
  90.     kHexDigitKeyBit = 2;
  91.     kEditKeyBit = 3;
  92.     kNonControlKeyBit = 4;
  93.     kCommandKeyBit = 5;
  94.     kCancelKeyBit = 6;
  95.     kAcceptKeyBit = 7;
  96.  
  97.     { Masks for bits in the flags in ClassifyKey }
  98.     
  99.     kDigitKey = 1;
  100.     kLetterKey = 2;
  101.     kHexDigitKey = 4;
  102.     kEditKey = 8;
  103.     kNonControlKey = 16;
  104.     kCommandKey = 32;
  105.     kCancelKey = 64;
  106.     kAcceptKey = 128;
  107.  
  108. (*******************************************************************************
  109. * Types
  110. *******************************************************************************)
  111.  
  112. TYPE
  113.  
  114. (*******************************************************************************
  115. * Types
  116. *
  117. * FileLikeSpec is a record declared the same as an FSSpec, but they're not
  118. * equivalent records, meaning you have to use a little effort to pass
  119. * FileLikeSpec to an FSSpec File Manager routine. This is as it should be,
  120. * because we're using this as a convenient storage facility, not necessarily
  121. * as something created with MakeFSSpec, and it's important to not pass
  122. * hand-made FSSpec records to the File Manager.    This largely comes in
  123. * handy for changing FSSpec records we get from the system into a format we
  124. * can use instead of the other way around.
  125. ********************************************************************************)
  126.  
  127.     FileLikeSpec = RECORD
  128.         vRefNum: INTEGER;
  129.         parID: LONGINT;
  130.         name: Str63;
  131.         END;
  132.     FileLikeSpecPtr = ^FileLikeSpec;
  133.  
  134. (*******************************************************************************
  135. * Global variables maintained by this unit
  136. *******************************************************************************)
  137.  
  138. VAR
  139.     gUntitledWindowCount: LONGINT;     { count of windows we've opened this
  140.                                       session }
  141.  
  142. (*******************************************************************************
  143. * Types -- we declare an EventRecord pointer for efficiency
  144. *******************************************************************************)
  145.  
  146. TYPE
  147.  
  148.     EventRecordPtr = ^EventRecord;
  149.  
  150. (*******************************************************************************
  151. *
  152. * IsDAWindow - returns TRUE if the window passed is a desk accessory window.
  153. *              Only needed for 6.0.7 systems not using MultiFinder.
  154. *
  155. *******************************************************************************)
  156.  
  157. FUNCTION IsDAWindow(window: WindowPtr): BOOLEAN;
  158.  
  159. (*******************************************************************************
  160. *
  161. * IsAppWindow - returns TRUE if the window passed is a window that belongs
  162. *                to our application
  163. *
  164. *******************************************************************************)
  165.  
  166. FUNCTION IsAppWindow(window: WindowPtr): BOOLEAN;
  167.  
  168. (*******************************************************************************
  169. *
  170. * ClassifyKey - returns information about a keystroke
  171. *
  172. * This routine takes an event record and returns a two-byte INTEGER full of
  173. * bit flags (defined above) telling what kind of keypress it was -- an
  174. * editing key, command key, digit key, etc.  Very useful for filter procedures
  175. * in dialogs.
  176. *
  177. *******************************************************************************)
  178.  
  179. FUNCTION ClassifyKey(theEventPtr: EventRecordPtr): INTEGER;
  180.  
  181. (*******************************************************************************
  182. *
  183. * OKToInteract - checks to see if user interaction is allowed
  184. *
  185. * This routine checks AEInteractWithUser to see if it's OK to talk to the user
  186. * about something, and prepares to do user interaction if it is by setting
  187. * the arrow cursor.
  188. *
  189. *******************************************************************************)
  190.  
  191. FUNCTION OKToInteract: BOOLEAN;
  192.  
  193. (*******************************************************************************
  194. *
  195. * MustInteract - requires user interaction
  196. *
  197. * This routine calls AEInteractWithUser with no timeout, never returning until
  198. * it's ok to interact with the user.
  199. *
  200. *******************************************************************************)
  201.  
  202. PROCEDURE MustInteract;
  203.  
  204. (*******************************************************************************
  205. *
  206. * AlertUser - tell the user about something
  207. *
  208. * This routine takes a resource ID of an 'ALRT' resource, and presents the
  209. * user with that Alert, ignoring what Button is pressed.  Handy for telling
  210. * the user things, but not for getting any input back.
  211. *
  212. *******************************************************************************)
  213.  
  214. PROCEDURE AlertUser(alertNum: INTEGER);
  215.  
  216. (*******************************************************************************
  217. *
  218. * AskUser - ask the user about something
  219. *
  220. * This routine takes a resource ID of an 'ALRT' resource, and presents the
  221. * user with that Alert, returning TRUE if the user picked the default button
  222. * (item #1).
  223. *
  224. *******************************************************************************)
  225.  
  226. FUNCTION AskUser(alertNum: INTEGER): BOOLEAN;
  227.  
  228. (*******************************************************************************
  229. *
  230. * DoPromptSave - find out if the user wants to save a file
  231. *
  232. * This routine presents an alert of the form "Save the <application name>
  233. * document <theName> before <closing/quitting>?   Don't Save/cancel/Save".
  234. * The action is either kClosing or kQuitting, and the return value is
  235. * either kSave, kCancel or kDontSave.  This routine calls MustInteract
  236. * because no default answer to this question is really safe.
  237. *
  238. *******************************************************************************)
  239.  
  240. FUNCTION DoPromptSave(theName: Str63; theAction: INTEGER): INTEGER;
  241.  
  242. (*******************************************************************************
  243. *
  244. * HandleFileError - tell the user about file errors
  245. *
  246. * HandleFileError alerts users to common file errors and also gives a generic
  247. * alert for things we weren't actually prepared to handle.  The error is the
  248. * first parameter, and the window we're working with is the second so the
  249. * dialogs can say things like "You can't save the document <windTitle> because
  250. * the disk is write-protected, bozo."  Or maybe slightly more polite.
  251. *
  252. *******************************************************************************)
  253.  
  254. PROCEDURE HandleFileError(myErr: OSErr; windTitle: Str255);
  255.  
  256. (*******************************************************************************
  257. *
  258. * CheckRequiredAEParms - see if we processed an Apple Event correctly
  259. *
  260. * This routine looks for the keyMissingKeywordAttr in an Apple Event record,
  261. * which is only present if we did _not_ process all the required parameters.
  262. * If it's not present, things are fine and it returns noErr.  Otherwise,
  263. * there was a missing parameter and it returns errAEEventNotHandled.
  264. * Note that this is really a pointer to an AppleEvent record -- Pascal passes
  265. * all parameters bigger than four bytes by reference.  I'd make this more
  266. * explicit by using an "AppleEventPtr" type except one isn't defined, and
  267. * defining it here probably isn't that useful.
  268. *
  269. *******************************************************************************)
  270.  
  271. FUNCTION CheckRequiredAEParms(theAppleEvent: AppleEvent): OSErr;
  272.  
  273. (*******************************************************************************
  274. *
  275. * CreateWindowTitle - make a title for a new window
  276. *
  277. * This routine creates a string suitable for window titles such as "untitled",
  278. * "untitled 2", etc. as specified by Macintosh Human Interface Guidelines.
  279. * You pass an existing string and CreateWindowTitle replaces it with your
  280. * new title.
  281. *
  282. *******************************************************************************)
  283.  
  284. PROCEDURE CreateWindowTitle(VAR theString: Str63);
  285.  
  286. (*******************************************************************************
  287. *
  288. * DoCopyResource - copy a resource from one file to another
  289. *
  290. * This routine is from Inside Macintosh: Macintosh Toolbox Essentials.  It
  291. * copies a resource of type theType and ID theID from resource file source
  292. * to resource file dest, returning any error.
  293. *
  294. *******************************************************************************)
  295.  
  296. FUNCTION DoCopyResource(theType: ResType; theID, source, dest: INTEGER): OSErr;
  297.  
  298. (*******************************************************************************
  299. *
  300. * DeviceLoopSim - simulate DeviceLoop when it's not present
  301. *
  302. * This routine is from issue #10 of _develop_, the Apple Technical Journal.
  303. * It's Forrest Tanaka's routine to simulate the DeviceLoop trap for machines
  304. * that have color QuickDraw but not DeviceLoop (in other words, System 6
  305. * machines).
  306. *
  307. *******************************************************************************)
  308.  
  309. PROCEDURE DeviceLoopSim(drawingRgn: RgnHandle; drawingProc: Ptr;
  310.                         userData: LONGINT; flags: LONGINT);
  311.  
  312. (*******************************************************************************
  313. *
  314. * NewPrJobMerge - merge job-specific parameters of two print records
  315. *
  316. * This routine is from Macintosh Technical Note "Fun with PrJobMerge" and
  317. * works around a bug in LaserWriter 7.x that makes the real PrJobMerge
  318. * sometimes damage your original print record.
  319. *
  320. *******************************************************************************)
  321.  
  322. PROCEDURE NewPrJobMerge(hPrintSrc, hPrintDst: THPrint);
  323.  
  324. (*******************************************************************************
  325. *
  326. * GetNextWindow - find the next window in the window list
  327. *
  328. * This routine returns the window immediately below the specified window.
  329. *
  330. *******************************************************************************)
  331.  
  332. FUNCTION GetNextWindow(theWindow: WindowPtr): WindowPtr;
  333.  
  334. (*******************************************************************************
  335. *
  336. * UpdateAllAppWindows - completely draw all of our document windows
  337. *
  338. * UpdateAllAppWindows goes through all windows we have and makes sure that
  339. * none of them have any pending updates.
  340. *
  341. *******************************************************************************)
  342.  
  343. PROCEDURE UpdateAllAppWindows;
  344.  
  345. IMPLEMENTATION
  346.  
  347. {$I SampleUtilities.inc1.p}
  348.  
  349. END.
  350.